package lumis.portal.url;

import lumis.portal.PortalException;
import lumis.portal.page.cache.PageCacheConfig;

/**
 * Interface implemented by factories of {@link WebResource}. These
 * factories are responsible for generating transient <code>WebResource</code>
 * instances as demanded, but have no direct responsibility over their 
 * life-cycle.
 *
 * @version $Revision: 10825 $ $Date: 2009-08-04 12:36:40 -0300 (Tue, 04 Aug 2009) $
 * @since 5.0.0
 */
public interface IWebResourceFactory
{
	/**
	 * Creates a {@link WebResource} instance based on a dynamic path.
	 * @param dynamicPath the dynamic path.
	 * @return the web resource.
	 * @throws IllegalArgumentException if <code>dynamicPath</code> is not a
	 * valid web resource dynamic path for this factory.
	 * @since 5.0.0
	 */
	public WebResource createWebResourceByDynamicPath(String dynamicPath) throws PortalException;

	/**
	 * Sets the file path for a {@link PageCacheConfig}.
	 * @param pageCache the page cache.
	 * @since 5.0.0
	 */
	public void setPageCacheFilePath(PageCacheConfig pageCache) throws PortalException;
	
	/**
	 * Returns if the cache is enabled for a web resource.
	 * @param webResource the web resource.
	 * @return <code>true</code> if the cache is enabled, <code>false</code> otherwise.
	 * @since 5.0.0
	 */
	public boolean isCacheEnabled(WebResource webResource) throws PortalException;

	/**
	 * Sets missing data in the web resources of the specified resource.
	 * @param resourceId the resource owner of the web resources.
	 * @param processChildren indicates if web resources of children resources
	 * should also be processed.
	 * @since 5.0.0
	 */
	public void setWebResourcesMissingData(String resourceId, boolean processChildren) throws PortalException;
	
	/**
	 * Adjusts a friendly path that has been resolved for a web resource.
	 * @param webResource the web resource.
	 * @param friendlyPath the resolved friendly path.
	 * @return the adjusted friendly path value.
	 * @since 5.0.0
	 */
	public String adjustResolvedFriendlyPath(WebResource webResource, String friendlyPath);

	/**
	 * Adjusts a friendly path due to clash.
	 * @param originalFriendlyPath the original friendly path resolved.
	 * @param clashedFriendlyPath the last clashed friendly path value.
	 * @param numRetry the number of retry for adjust clashing for this friendly
	 * path. In each call to this method for resolving a single friendly path this 
	 * value is incremented.
	 * @return the adjusted friendly path value.
	 * @since 5.0.0
	 */
	public String adjustFriendlyPathForClash(String originalFriendlyPath, String clashedFriendlyPath, int numRetry);
}
